[% setvar title Components in the Perl Core Should Have Well-Defined APIs and Behavior %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Components in the Perl Core Should Have Well-Defined APIs and Behavior</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Bradley M. Kuhn &lt;<a href='mailto:bkuhn@ebb.org'>bkuhn@ebb.org</a>&gt;
  Date: 17 Aug 2000
  Last Modified: 28 Sep 2000
  Mailing List: <a href='mailto:perl6-internals@perl.org'>perl6-internals@perl.org</a> 
  Number: 125
  Version: 2
  Status: Frozen</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Perl has a number of native data structures, as well as standard core
libraries that operate on those data structures.  All components that are
needed to make perl, &quot;Perl&quot;, should have well-defined APIs and behavior.
These APIs should be documented separately from the implementation, in a
language-independent and an object-oriented way.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<a name='Introduction'></a><h2>Introduction</h2>
<p><i><a href='http://search.cpan.org/perldoc?RFC35'>RFC35</a></i> has already begun to discuss some of the ways perl might keep track
of its internal data.  This RFC, by contrast, looks at the problem of Perl's
internal data (and core libraries) from a much higher level.</p>
<p>Perl has a number of native data structures (e.g., scalar, array, hash,
sub), as well as standard core libraries (e.g., print, substr, keys) that
operate on these data structures.  Each of these components has some sort of
interface.  For <b><i>perl5</i></b>, these interfaces were loosely documented in the
source, occasionally in the POD documentation files, and sometimes in
additional documents such as the Perl Guts Illustrated.</p>
<p>However, the documentation of the APIs in <b><i>perl5</i></b> was not really designed
to help new implementers.  It was designed either as user documentation or
as work-in-progress attempts to keep track of the increasingly changing code
of <b><i>perl5</i></b>.</p>
<p>With this new implementation, we should work towards a development
environment where the code is secondary to the API.  We have shown that the
model of &quot;the reference is the implementation&quot; can no longer work for a
complex language such as Perl.  We do not want ANSI-style bureaucracy, but
we should still seek a way to provide documentation of the Perl internals
separate from the implementation.</p>
<a name='Primary Advantages'></a><h2>Primary Advantages</h2>
<p>An internals API that is separate from the implementation will provide the
following advantages:</p>
<ul>
<li><a name='Reimplementation of a component can be done independently and more easily when necessary, since the behavior of each component is well-defined.'></a>Reimplementation of a component can be done independently and more easily
when necessary, since the behavior of each component is well-defined.</li>
<li><a name='Parallel implementations can easily be developed. This is an important feature for porting Perl to architectures for which reasonable C compilers are not available, such as the Java Virtual Machine. In addition, developing parallel implementations allows for experimentation, and radically different implementation ideas can be easily compared.'></a>Parallel implementations can easily be developed.  This is an important
feature for porting Perl to architectures for which reasonable C compilers
are not available, such as the Java Virtual Machine.  In addition,
developing parallel implementations allows for experimentation, and
radically different implementation ideas can be easily compared.</li>
<li><a name='Perl is special in part because its internal data structures provide amazing external features. Well-defined APIs will perhaps make it possible for Perl's data structures to be used in ways above and beyond perl itself.'></a>Perl is special in part because its internal data structures provide amazing
external features.  Well-defined APIs will perhaps make it possible for
Perl's data structures to be used in ways above and beyond perl itself.</li>
<li><a name='The learning curve for new core developers to learn the perl internals will be greatly reduced. Any good programmer can read and understand API documentation. That API documentation will provide a roadmap for understanding why the core is laid out in a particular way. Since the API documentation will come first, it will rarely be incomplete.'></a>The learning curve for new core developers to learn the perl internals will
be greatly reduced.  Any good programmer can read and understand API
documentation.  That API documentation will provide a roadmap for
understanding why the core is laid out in a particular way.  Since the API
documentation will come first, it will rarely be incomplete.</li>
</ul>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<a name='An Object-Oriented and Language-Independent Approach'></a><h2>An Object-Oriented and Language-Independent Approach</h2>
<p>An object-oriented approach to an API is not perfect.  However, in this
case, nearly all the behaviors of Perl's internal objects are well
understood.  In addition, in <b><i>perl5</i></b>, the internals are already roughly
object-oriented.  Thus, an object-oriented approach is reasonable in this
case.</p>
<p>We should not tie this API documentation to any particular language, lest we
be influenced by the object-oriented features supported by that language.
Instead, we should document the API using terminology borrowed from any
object-oriented language or design methodology that seems appropriate.  Such
a mix should not be problematic, as long as we are internally consistent in
our use of the terminology.  Of course, some overriding methodology might be
chosen as a guiding force.</p>
<p>Building this object-oriented interface does not necessarily demand an
object-oriented implementation.  The API should be general, and should not
demand any particular implementation strategy.  Thus, choosing a simple
object-oriented approach for the API document does not limit future
implementation choices; it only defines the behavior that the internals must
provide.</p>
<a name='Format of the API Documentation'></a><h2>Format of the API Documentation</h2>
<p>This will be addressed in future RFCs after the langauge design process has
completed and the Internals Working Group no longer faces a moving target.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 35: A proposed internal base format for perl variables</p>
<p>Aas, Gisle.  &quot;Perl Guts Illustrated, Version 0.09&quot;. [Online] Available at
<b><i><a href='http://gisle.aas.no/perl/illguts/' target='_blank'>gisle.aas.no</a></i></b>. November 1999.</p>
</div>
